/*
 *    Copyright (c) 2018-2025, lengleng All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright
 * notice, this list of conditions and the following disclaimer in the
 * documentation and/or other materials provided with the distribution.
 * Neither the name of the pig4cloud.com developer nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 * Author: lengleng (wangiegie@gmail.com)
 */

package com.pig4cloud.pig.admin.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.pig4cloud.pig.admin.api.entity.SysPublicParam;
import com.pig4cloud.pig.common.core.util.R;

/**
 * 系统公共参数配置服务接口
 * <p>
 * 提供系统级公共参数的管理功能，包括参数的增删改查和缓存同步。
 * 支持动态配置系统运行参数，无需重启应用即可生效
 * </p>
 *
 * @author lengleng
 * @date 2025/05/30
 */
public interface SysPublicParamService extends IService<SysPublicParam> {

	/**
	 * 根据公共参数key获取对应的value值
	 * <p>
	 * 优先从缓存中获取参数值，缓存未命中则从数据库查询。
	 * 支持动态更新，修改后通过缓存同步立即生效
	 * </p>
	 * 
	 * @param publicKey 公共参数键名
	 * @return 参数值，未找到时返回null
	 */
	String getParamValue(String publicKey);

	/**
	 * 更新系统公共参数
	 * <p>
	 * 修改已有参数的值或新增参数，同时更新缓存。
	 * 参数key必须唯一，重复时会返回错误
	 * </p>
	 * 
	 * @param sysPublicParam 系统公共参数对象，包含key、value等信息
	 * @return 操作结果，包含成功状态和提示信息
	 */
	R updateParam(SysPublicParam sysPublicParam);

	/**
	 * 批量删除参数
	 * <p>
	 * 根据参数ID批量删除公共参数，同时清除相关缓存。
	 * 删除操作不可恢复，请谨慎使用
	 * </p>
	 * 
	 * @param publicIds 参数ID数组
	 * @return 删除结果，包含成功数量和失败原因
	 */
	R removeParamByIds(Long[] publicIds);

	/**
	 * 同步参数缓存
	 * <p>
	 * 将数据库中的所有公共参数重新加载到缓存中。
	 * 通常在参数变更后或缓存失效时使用，确保缓存与数据库一致
	 * </p>
	 * 
	 * @return 操作结果，包含同步成功的参数数量
	 */
	R syncParamCache();

}
